ref.: https://app.clickup.com/t/86ba2z5gz

Changes:

New Files

Modified Files

Design Decisions

• Single method interface — ITwoFactorAuditService::log(User, eventType, method, ipAddress, ?metadata) keeps the contract minimal and explicit. Validation of allowed event types
  and methods is delegated to TwoFactorAuditLog entity setters (throws InvalidArgumentException on unknown values).

• Sync persistence — the audit log is flushed immediately ($repository->add($log, true)) to guarantee the record lands before the request finishes, regardless of OTEL availability.

• OTEL is optional — EmitAuditLogJob is only dispatched when opentelemetry.enabled is true, keeping the happy path free of queue overhead in environments where telemetry is
  disabled.

• two_factor.success derivation — only EventChallengeFailed maps to false; every other event type (issued, succeeded, device-trusted, etc.) is treated as a
  successful/informational outcome.

OTLP Attributes Emitted

When OpenTelemetry is enabled the following structured attributes are sent under
the two_factor.audit message:

Tests

tests/Unit/TwoFactorAuditServiceTest.php

Requested GOAL

Current state

No 2FA-specific audit service exists. MFA events would be inconsistently logged or only visible through generic application logs.

Target state

TwoFactorAuditService provides a centralized audit primitive that persists TwoFactorAuditLog records and emits OTLP audit attributes through the existing fntech-audit pipeline.

This ticket provides audit infrastructure only. It does not wire audit calls into controller methods, strategies, or device-trust flows. That wiring belongs to Ticket 9/10, where the real MFA flow exists.

TASKS

• Create ITwoFactorAuditService interface with:
  • log(User $user, string $eventType, string $method, string $ipAddress, ?array $metadata = null): void
• Implement TwoFactorAuditService.
• Validate eventType against:
  • challenge_issued
  • challenge_succeeded
  • challenge_failed
  • enrollment_changed
  • device_trusted
  • device_revoked
  • recovery_used
  • settings_changed
• Validate method against:
  • email_otp
  • sms_otp
  • totp
  • passkey
  • recovery
• Create and persist TwoFactorAuditLog entity.
• Store metadata as JSON/null.
• Capture user_agent from request context when available, or accept a future method signature change if project conventions require explicit user_agent.
• Emit OTLP attributes following existing fntech-audit pipeline conventions:
  • two_factor.event_type
  • two_factor.method
  • two_factor.user_id
  • two_factor.ip_address
  • two_factor.success
  • two_factor.device_trusted
• Register ITwoFactorAuditService in TwoFactorServiceProvider.
• Write unit test: log() persists TwoFactorAuditLog with correct fields.
• Write unit test: log() emits OTLP attributes.
• Write unit test: log() accepts null metadata.
• Write unit test: invalid event type throws InvalidArgumentException.
• Write unit test: invalid method throws InvalidArgumentException.

ACCEPTANCE CRITERIA

• log() persists TwoFactorAuditLog with all required fields.
• Valid event types are accepted.
• Invalid event types are rejected.
• Valid methods are accepted.
• Invalid methods are rejected.
• Metadata null is stored as null.
• Metadata array is JSON-serializable and stored correctly.
• OTLP attributes match project audit conventions.
• Service is injectable via ITwoFactorAuditService.
• All unit tests pass.

DEVELOPMENT NOTES

Key files:

• New: app/Services/Auth/ITwoFactorAuditService.php
• New: app/Services/Auth/TwoFactorAuditService.php
• New: tests/Unit/TwoFactorAuditServiceTest.php
• Modified: app/Providers/TwoFactorServiceProvider.php

Gotchas:

• This service is a primitive. It should not know about UserController::verify2FA(), verify2FARecovery(), resend2FA(), or concrete MFA flow ordering.
• Do not add controller/strategy integration tests here. Integration belongs in Ticket 9/10.
• Follow existing audit pipeline patterns rather than inventing a new OTLP abstraction.

Risks:

• Risk: audit service becomes a dumping ground for MFA orchestration. Mitigation: keep API limited to log().

Out of scope:

Controller wiring, strategy wiring, device-trust wiring, Elastic dashboards, audit UI, retention policy.

Summary by CodeRabbit

Release Notes

• New Features

  • Added audit logging for two-factor authentication events, including tracking of authentication methods, client IP addresses, and optional metadata.
  • Integrated with OpenTelemetry for enhanced observability when enabled.

• Tests

  • Added comprehensive unit tests covering audit log persistence, telemetry emission, and validation of event types and methods.